Перейти к основному содержимому

Чек-лист — создавать так чтобы сразу работало

Версия: 1.0 Дата: 25.04.2026 Статус: Готов к обсуждению

Чек-лист обязательных проверок при создании или правке любого документа или конфига в стеке Docusaurus + Decap CMS + DocMap MCP. Без угадывания, без каскадных правок, без регрессий.

Главный принцип​

Каждый создаваемый документ или вносимая правка должны работать с первого раза в реальной системе. Не «потом проверим», не «надеюсь сработает».

Это достигается через обязательный чек-лист перед записью + проверка сразу после записи.

Чек-лист перед созданием нового документа​

1. Frontmatter — точный шаблон​

---
title: "Название документа на русском (английский термин в скобках при необходимости)"
draft: false
---

Проверка:

  • ✅ title: в двойных кавычках;
  • ✅ draft: false обязателен (иначе документ не виден в production);
  • ✅ Никаких legacy-полей (sidebar_position, sidebar_label, id, slug) — кроме случаев с явным обоснованием;
  • ✅ Парные --- сверху и снизу;
  • ✅ Кодировка UTF-8 без BOM.

2. Шапка документа​

После H1 через обязательную пустую строку:

# Название документа на русском

**Версия:** 1.0
**Дата:** ДД.ММ.ГГГГ
**Статус:** Готов к обсуждению

Проверка:

  • ✅ Между H1 и **Версия:** обязательная пустая строка (Decap CMS body parser требует);
  • ✅ H1 идентичен title: во frontmatter (без кавычек);
  • ✅ Статус один из: Черновик / Готов к обсуждению / Утверждён / Черновик (архивная версия).

3. MDX-безопасность​

Перед записью — мысленный grep <digit и >digit:

  • ❌ <2s, <500ms, <15 min, >2 сервиса, <TagName> в plain-тексте;
  • ✅ &lt;2s, &lt;500ms, &gt;2 сервиса;
  • ✅ Внутри `<2s` (backtick-инлайн) — безопасно;
  • ✅ Внутри ``` ``` (fenced code) — безопасно.

При сомнении — после записи grep -nE '<[0-9]'. Если находки в plain-тексте — sed -i 's/<\([0-9]\)/\&lt;\1/g'.

Подробности — в MDX-безопасное написание.

4. Язык​

  • ✅ Только русский язык в основном тексте;
  • ✅ Английские термины в скобках при первом упоминании: «коммерческая фиксация (quote, quoted promise)»;
  • ✅ Никакого смешения языков в одном предложении;
  • ✅ Имена сущностей в коде/JSON/YAML на английском (как в реальной системе);
  • ✅ Заголовки H1-H6 на русском, английский в скобках при необходимости.

5. Связи с другими документами​

  • ✅ Раздел ## Связанная документация в конце документа;
  • ✅ В тексте — явные markdown-ссылки на верхнеуровневые документы и соседние reference-документы;
  • ✅ Никаких «висящих» утверждений без обоснования и ссылки.

6. Размещение документа​

  • ✅ Документ в одном из четырёх стандартных разделов: overview/ / reference/ / operations/ / development/;
  • ✅ Не в корне проекта (docs/<slug>/);
  • ✅ Не в корне docs/.

Чек-лист после создания документа​

docs_search(ключевое_слово_из_документа, project="<slug>")

Документ должен появиться в результатах — это подтверждает, что DocMap watcher переиндексировал.

2. Проверка MDX-safe через grep​

grep -nE '<[0-9]' путь/к/файлу.md
grep -nE '>[0-9]' путь/к/файлу.md

Оба должны вернуть либо пустой результат, либо только совпадения внутри backtick-инлайна или fenced code blocks.

3. Если документ — новый файл, обновить index.md проекта​

tools/build_project_index.sh <project-slug>

Обновляет автогенерируемый index.md проекта. Запрещено редактировать index.md напрямую — только через скрипт.

4. Если документ создаёт новые backlinks — проверить связи​

docs_links(section_id, direction="both")

Убедиться, что ссылки на другие документы разрешились корректно (нет unresolved).

Чек-лист при правке существующего документа​

Перед docs_patch_section:

  1. Сначала прочитать текущий контекст: docs_get_section нужной секции и соседних секций.
  2. Понять, что изменится: обновить только нужное.
  3. Не менять структуру header-path: docs_patch_section обновляет только тело, не заголовок секции.
  4. Поднять **Версия:** и **Дата:** в шапке (если изменение существенное).
  5. MDX-safe self-check на новом теле перед записью.
  6. После записи — docs_links для проверки целостности обратных ссылок.

Чек-лист при архивации документа​

Полная процедура — в Архивация документов — никогда не удалять.

Сжатый порядок:

  1. docs_rename_file <file>.md → <file>-old-YYYY-MM-DD.md.
  2. docs_patch_section шапки — обновить title: (добавить «архивная версия»), статус → Черновик (архивная версия), добавить блок-цитату с предупреждением и ссылкой на новый документ.
  3. Никогда не удалять содержимое архивного документа.
  4. Создать новый документ через docs_create_file.
  5. Обновить backlinks при необходимости.

Чек-лист при правке инфраструктурных конфигов​

Конфиги вроде ecosystem.config.js, docusaurus.config.ts, cms-config.json, nginx — это продакшен-конфиги системы.

Перед правкой​

  1. Доказать причину поломки через curl/логи/прямой тест:

    • Что именно не работает?
    • Какой именно компонент отдаёт неправильный ответ?
    • Почему он его отдаёт (логи, env, состояние)?

  2. Локализовать — менять только компонент, который доказанно сломан. Не трогать компоненты, которые работают (даже если есть гипотеза, что они «могут быть» причиной).

  3. Сохранить оригинал перед правкой:

    cp <config-file> <config-file>.bak.YYYY-MM-DD-HHMM

    Для восстановления при провале правки.

При правке​

  1. Минимальная инвазивность — менять только нужную строку, не реструктурировать весь конфиг.
  2. Понять, что меняется и почему — каждое изменение тезисно обосновано.
  3. Соблюдать архитектурные ограничения системы:
    • cms-config.json admin.password_hash — только через tools/add_user.sh --admin;
    • _project_.json access[] — только через tools/add_user.sh;
    • index.md проекта — только через tools/build_project_index.sh;
    • docusaurus.config.ts url/title — только через cms-config.json;
    • static/admin/index.html CREDENTIALS_HASH — только через tools/add_user.sh --admin.

После правки​

  1. Перезапустить затронутый сервис (для PM2 при смене env — pm2 delete + pm2 start ecosystem.config.js --only <name>, не restart).
  2. Проверить через curl/логи, что цель правки достигнута.
  3. Если регрессия — немедленный откат, не дальнейшие правки поверх.
  4. pm2 save после успешной правки pm2-конфига (для переживания reboot).
  5. Сообщить пользователю что сделал и попросить проверить.

Подробности диагностики CMS — в Диагностика CMS — порядок проверок.

Запрещённые паттерны​

  • ❌ Каскад правок без проверки между ними («попробую ещё это», «попробую вот так»);
  • ❌ Изменение рабочего конфига на основании гипотезы без доказательства;
  • ❌ «Улучшение» того, что работает («сделаю по-моему лучше»);
  • ❌ Запись документа без MDX-safe проверки;
  • ❌ Запись документа без draft: false во frontmatter;
  • ❌ Запись документа без пустой строки между H1 и шапкой;
  • ❌ Архивация без docs_rename_file + статус Черновик (архивная версия);
  • ❌ Изменение index.md проекта вручную (только через tools/build_project_index.sh).

Реальный случай для памяти​

25 апреля 2026 — провал каскадной правки CMS:

  1. CMS не работала: ошибка <!DOCTYPE html> в YAML-парсере браузера.
  2. Найдена реальная причина: decap-server крэшится из-за EADDRINUSE на 8081 (Apache занял порт), env PORT=8083 не подхватывается через pm2 restart --update-env.
  3. Правильное действие: pm2 delete cms-decap-server + pm2 start ecosystem.config.js --only cms-decap-server. Backend заработал, curl -X POST http://localhost:8083/api/v1 отдаёт корректный JSON.
  4. Ошибочное действие: не убедившись, что фикс backend-а решил проблему в браузере, агент дополнительно изменил args: для Docusaurus на --host 0.0.0.0 --port 3000 — гипотеза «может, WSL2 не пробрасывает 127.0.0.1». Гипотеза не была проверена.
  5. Результат: пользователь получил ту же ошибку в браузере, плюс потенциально новые регрессии.
  6. Корректный откат: возврат args: 'start' обратно в ecosystem.config.js, перезапуск через pm2.

Что должно было быть: после фикса decap-server остановиться, дать пользователю проверить браузер, и только при сохранении проблемы продолжить диагностику. Реальная причина CMS-ошибки в итоге оказалась проще: открывать http://localhost:3000/admin/index.html вместо /admin/ — это документировано в Стандарт работы с системой документации.

Урок: при проблеме с инфраструктурой — сначала прочитать существующий стандарт системы (он в DocMap), потом действовать. Не каскадные правки.

Связанная документация​